
=HTTPSession Overlay=

The HTTPSession overlay inserts a space into the request context that
processes the <code>session:</code> scheme.
The overlay maintains separate <code>session:</code> spaces in memory
and automatically associates the space that correlates to the HTTP Cookie
present in the external HTTP request.

{endpoint}jetty.HTTPSession{/endpoint}


==Configuration==

To provide <code>session:</code> spaces to an application space,
wrap an application space with the HTTPSession overlay as shown in the following example:

{xml}
<overlay>
	<prototype>HTTPSession</prototype>
	<config>
		<maxSessions>500</maxSessions>
		<expiryPeriod>300000</expiryPeriod>
	</config>
	<space>
		Application Space
	</space>
</overlay>
{/xml}

Where the config parameter is an XML document like...

{xml}
<config>
	<maxSessions>20</maxSessions>
	<minDuration>300000</minDuration>
	<maxDuration>3000000</maxDuration>
	<cookiePath>/tools/apposite/</cookiePath>
	<autoReconnect>true</autoReconnect>
</config>
{/xml}

* maxSessions - the maximum number of {authornote}simultaneous{/authornote} sessions permitted.
* expiryPeriod - the maximum time in milliseconds that a session can remain untouched before it will be garbage collected. {authornote}Is this a hard-collect?{/authornote}... {authornote}Actually, I don't see this anymore in the generated documentation{/authornote}
* cookiePath - {authornote}How is this used? What does it mean?{/authornote}
* autoReconnect - {authornote}Not sure how you would connect if this is false and you need to use the session. Why have this parameter?{/authornote}
* minDuration - {authornote}???{/authornote}
* maxDuration - {authornote}???{/authornote} 

{authornote}What happens if the max session is exceeded?{/authornote}

'''Note''': the HTTPSession overlay '''must''' itself be wrapped 
by the [[doc:tpt:http:HTTPBridge|HTTPBridge]] overlay at some point in the superstack.

==session:==

Within the wrapped application space, requests may be made to the
<code>session:</code> URI scheme based space using
a standard REST path and the verbs SOURCE, SINK, DELETE and EXISTS.
Any state changes made in the <code>session:</code> space
are kept in memory an are available
for the duration of the current request.
The <code>session:</code> space is associated with a particular
HTTP Cookie. 
When a subsequent HTTP request includes that cookie, this saved
<code>session:</code> is associated with that request along will
all of the saved state.

For example, the following code will store a representation in
session space for future use:

{java}request = context.createRequest("session:/id");
request.setPrimaryArgument(representation);
request.setVerb(INKFRequestReadOnly.VERB_SINK);
context.issueRequest(request);
{/java}

To retrieve this information later while processing a subsequent HTTP
request, use the following code:

{java}Object representation = context.source("session:/id");
{/java}

===SOURCE===

The SOURCE verb is used to retrieve a representation from
the <code>session:</code> space.
For example, to retrieve an previously saved representation:

{java}Object representation = context.source("session:/id");{/java}

===SINK===

The SINK verb is used to place a representation into
the <code>session:</code> space.
For example, the following code saves a representation 
for later use:

{java}context.sink("session:/id", representation){/java}


===EXISTS===

The EXISTS verb is used to test for the presence of a
specific representation in the <code>session:</code> space.
For example, the following code tests to see if a
representation for <code>session:/id</code> is present:

{java}if (context.exists("session:/id"))
  {
  ...
  }
{/java}


===DELETE===

The DELETE verb is used with a request to remove state from the 
<code>session:</code> space or all information at once
by using just the URI scheme.

For example, to delete a specific representation:

{java}context.delete("session:/id");{/java}

For example, to delete all representations in the <code>session:</code>
space:

{java}context.delete("session:");{/java}

In addition to using the 


==Session Metadata==

We need to describe active:httpSessionStatus


